# gpxtools

A collection of command line tools for using GPX files written in C++.

General requirements:
  * [Expat](https://libexpat.github.io/) for XML parsing
  * [CMake](https://cmake.org/) for building

## gpxls

```text
Usage: gpxls [OPTION].. [FILE]..
List summary or full information from GPX-files.
gpxsplit.cpp
   -?, --help      display this help and exit
       --version   display version and exit
   -s, --summary   display summary information
   -f, --full      display full information with elevation (m), time and distance (m)
   -e, --extend    extend the full display with the calculated bearing and speed (km/h)

List the contents of GPX-files
```

Examples:
```text
gpxls track.gpx

  Display a summary of the track.gpx file: the waypoints, routes, tracks and track 
  segments information.

gpxls -f track.gpx

  Display full information of the track.gpx file: the waypoints, routes, route points, 
  tracks, track segments and track points.

gpxls -f -e track.gpx

  Display full information of the track.gpx file: the waypoints, routes, route points, 
  tracks, track segments and track points. Display for the track points also the
  calculated bearing and speed.
```
---

## gpxjson

```text
Usage: gpxjson [OPTION].. [FILE]
Convert a GPX-file to GeoJson or plain json.

   -?, --help                        display this help and exit
       --version                     display version and exit
   -w, --waypoints                   convert the waypoints
   -t, --tracks                      convert the tracks
   -r, --routes                      convert the routes
   -f, --format=geojson|plain        set the output format (def:geojson)
   -m, --mode=compact|normal         set the output mode (def:normal)
   -c, --coordinates=lonlat|latlon   set the type of coordinates for plain format (def:lonlat)
   -p, --points=NUMBER               set the number of points per line in normal mode (def:4)
   -s, --simplify=METRES             simplify the route by track distance

Convert the waypoints, route points and/or track points in a GPX-file to a GeoJson-file or plain json file.
```

Examples:
```text
gpxjson -w -m compact track.gpx >output.json

  Convert the waypoins in the track.gpx file to Multipoints in the output.json file. All points are on the
  same line (compact mode).

gpxjson -t -m normal -n 6 track.gpx >output.json

  Convert the track points in the track.gpx to MultiLinestrings in the output.json file. All points are
  grouped by 6 per line (normal mode).

gpxjson -r -m normal

  Read the route points from standard in and convert them to MultiLinestrings that are written to
  standard out in normal mode (4 points per line).

gpxjson -t -f plain -m compact -s 0.1 track.gpx >output.json

  Convert the track point in track.gpx to a plain json array with lon,lat points after simplifying the
  track based on continuing removing points which add less then 0.1 metres to the total track distance.

gpxjson -t -f plain -m compact -c latlon -s 0.1 track.gpx >output.json

  Convert the track point in track.gpx to a plain json array with lat,lon points after simplifying the
  track based on continuing removing points which add less then 0.1 metres to the total track distance.
```
---

## gpxcoord

```text
Usage: gpxcoord [OPTION].. [LAT LON]..
Display the LAT LON gps coordinate in different formats.

   -?, --help              display this help and exit
       --version           display version and exit
   -b, --browser=BROWSER   set the browser

Show all formats for gps coordinates and optional the location in the browser.

Examples for gps coordinate formats:
         51.90540,     4.46660
        -51.90540,    -4.46660
      N 51 54.324,  E 4 27.996
      51 54.324 S,  4 27.996 W
     N 51 54 19.4, E 4 27 59.8
     51 54 19.4 S, 4 27 59.8 W
```

Examples:

```text
gpxcoord 51.90540 4.46660

  Show all formats for the gps coordinates 51.90540,4.46660.

gpxcoord -b firefox "51 54.324 N" "4 27.996 E"

  Show all formats for the gps coordinates 51 54.324 N,4 27.996 E and show the location in the browser.

gpxcoord -- -51.90540 -4.46660

  Show all formats for the gps coordinates -51.90540,-4.46660 (use -- to prevent parsing -51.90540 
  as parameter).
```
---

## gpxplot

```text
Usage: gpxplot [OPTION].. [FILE]
Generate a GnuPlot command file from a GPX-file on standard output.

   -?, --help             display this help and exit
       --version          display version and exit
   -t, --title=TITLE      set the title of the plot
   -x, --x=SOURCE         set the x-axis source (distance, time) (def:time)
   -y, --y=SOURCE         set the y-axis source (elevation, distance, speed) (def:speed)
   -p, --plot=STYLE       set the plot style (lines,..) (def:lines)
   -c, --color=COLOR      set the line color
   -m, --term=x11|qt|..   set the output device and options
   -w, --width=WIDTH      set the width of the plot
   -h, --height=HEIGHT    set the height of the plot
   -o, --output=FILE      set the output file of the plot

Generate a GnuPlot command file from the distance, elevation, speed and time in a GPX-file on standard output.
```

Examples:

```text
gpxplot -t "Track" -c "red" -o track.png -w 1024 -h 512 track.gpx | gnuplot

  Generate a command file for GnuPlot which will display a plot with time and speed from track.gpx 
  in a red line in a PNG image with the size 1024 x 512.

gpxplot -t "Track" -y elevation track.gpx >track.plt
gnuplot track.plt
  
  Generate a command file for GnuPlot which will display a plot with time and elevation from track.gpx
  in the default viewer.

gpxplot -t "Track" -o track.png -m "pngcairo enhanced font'Verdana,10'" -w 1024 -h 512 track.gpx | gnuplot

  Generate a command file for GnuPlot which will display a plot with time and speed from track.gpx 
  in a PNG image with the size 1024 x 512 using a specific terminal and its options.
```

Requirements:
  * [GnuPlot](http://www.gnuplot.info/) for plotting

---

## gpxrm

```text
Usage: gpxrm [OPTION].. [FILE]
Remove waypoint, track or route from GPX-file.

   -?, --help            display this help and exit
       --version         display version and exit
   -w, --waypoint=NAME   remove the waypoint with NAME
   -t, --track=NAME      remove the track with NAME
   -s, --segment=NR      remove only segment in track with NR
   -r, --route=NAME      remove the route with NAME

Remove waypoint, track or route from GPX-file and display the resulting file on standard output.
```

Note: Use gpxls to find the waypoint, track or route name.

Examples:
```text
gpxrm -t 'Track1' track.gpx >output.gpx

  Remove the track 'Track1' from the track.gpx file and store the result in output.gpx file.

gpxrm -t 'Track2' -s 2 track.gpx

  Remove the second tracksegment from the track 'Track2' in the track.gpx and display the
  result on standard output.
```

---

## gpxsplit

```text
Usage: gpxsplit [OPTION].. [FILE]
Split the track segments in a GPX-file.

   -?, --help                       display this help and exit
       --version                    display version and exit
   -a, --analyse                    analyse the file for splitting
   -d, --distance=METRES            split based on a distance
   -t, --time=YYYY-MM-DD HH:MM:SS   split based on a timestamp
   -s, --seconds=SEC                split based on a time difference in seconds
   -m, --minutes=MIN                split based on a time difference in minutes
   -h, --hours=HOURS                split based on a time difference in hours

Split the track segments in a GPX-file in multiple track segments based on distance or time 
and display the resulting GPX on standard output.
```

Examples:
```text
gpxsplit -a -d 4000 track.gpx

  Check if the track segments in the track.gpx file can be split based on a distance of
  4000 metres. gpxsplit reports the results, no GPX-file is written to standard output.

gpxsplit -d 4000 track.gpx

  Split the track segments in the track.gpx file based on the distance between track points
  of 4000 metres. The resulting GPX-file is written to standard output.

gpxsplit -t '2018-10-24 09:03:00' track.gpx >output.gpx

  Split the track segments in the track.gpx file based on the timestamps of the track points.
  The resulting GPX-file is written to output.gpx.
```

---

## gpxsim

```text
Usage: gpxsim [OPTION].. [FILE]
Simplify a GPX-file.

   -?, --help                display this help and exit
       --version             display version and exit
   -v, --verbose             display the results of the simplification
   -d, --distance=METRES     remove route or track points within distance of the previous point in METRES
   -n, --number=NUMBER       remove route or track points until the route or track contains NUMBER points
   -x, --crossTrack=METRES   remove route or track points with a cross track distance less than METRES

Simplify a route or track using the distance threshold and/or the Douglas-Peucker algorithm and display
the resulting GPX-file on standard output.
```

Examples:
```text
gpxsim -v -d 1 track.gpx

  Display the result of the simplification of the track.gpx after using the distance threshold,
  no GPX-file is written to standard output.

gpxsim -x 1 track.gpx

  Simplify the track.gpx file using the Douglas-Peucker algorithm. All points with a cross track
  distance of less than 1 metre are removed. The resulting GPX-file is written to standard output.

gpxsim -n 500 track.gpx >output.gpx

  Simplify the track.gpx file using the Douglas-Peucker algorithm until there are 500 points
  remaining. The resulting GPX-file is written to output.gpx.
```

---

## gpxcat

```text
Usage: gpxcat [OPTION].. [FILE]
Concat the track segments in a GPX-file.

   -?, --help              display this help and exit
       --version           display version and exit
   -d, --distance=METRES   concat only if both segments are less than METRES apart

Concatenate the track segments in a GPX-file and display the resulting GPX-file on standard output.
```

Examples:
```text
gpxcat track.gpx >output.gpx

  All track segments in the track.gpx file are concatenated per track and written to output.gpx.

gpxcat -d 12.0 track.gpx

  All track segments in the track.gpx file for which the distance between the end of the segment
  and the start of the next segment is smaller than 12 metres are concatenated per track. The
  resulting GPX-file is written to standard output.
```

---

## gpxgeotag

```text
Usage: gpxgeotag [OPTION].. [GPX-FILE] [JPG-FILE]
Geo tag the photo files with the GPX-files.

   -?, --help              display this help and exit
       --version           display version and exit
   -s, --seconds=SEC       the seconds offset for the time of the photos
   -m, --minutes=MIN       the minutes offset for the time of the photos
   -h, --hours=HOURS       the hours offset for the time of the photos

Geo tag the photos with the GPX-files, based on the time of the photos and the geopositions in the GPX-files.

Note: the tool expects the gpx extension for the GPX-files and the jpeg or jpg extension for the photo files.
      Files with other extensions are ignored.
```

Examples:
```text
gpxgeotag track.gpx *.JPG

  Geo tag all *.JPG files with the geopositions in the track.gpx file.

cat track.gpx | gpxgeotag -s -60 photo1.jpeg

  Geo tag the photo1.jpg with the geopositions read from stdin. The photo date and times are reduced
  by 60 seconds before matching.
```

Requirements:
  * [Exiv2](http://www.exiv2.org/) for setting the photo metadata.

---

## gpxfetch

```text
Usage: gpxfetch [OPTION].. [FILE]
Fetch a waypoint, track or route from a GPX-file.

   -?, --help            display this help and exit
       --version         display version and exit
   -w, --waypoint=NAME   fetch the waypoint with NAME
   -t, --track=NAME      fetch the track with NAME
   -r, --route=NAME      fetch the route with NAME

Fetch a waypoint, track or route from a GPX-file and display the resulting GPX-file with this waypoint, track or route on standard output.
```

Note: Use gpxls to find the waypoint, track or route name.

Examples:
```text
gpxfetch -t 'Track1' track.gpx >track1.gpx

  Fetch the track 'Track1' from the track.gpx file and store the track in track1.gpx file.
```

---

## gpxpath

```text
Usage: gpxpath [OPTION].. PATH [FILE]
Read or set a path from a GPX-file.

   -?, --help            display this help and exit
       --version         display version and exit
   -v, --value=VALUE     set path to a value

Read or set a path from a GPX-file and display the result on standard output.
```

Notes:
  * Use with care, always keep the original file
  * Extensions cannot be set
  * No checks for invalid values for the path
  * Layout of the GPX-file will be lost
  * Attributes cannot be read or set

Examples:
```text
gpxpath /gpx/metadata/desc track.gpx

  Show the value of the '/gpx/metadata/desc' path. If the path is not present in the GPX-file, ERRORLEVEL will be 1.

gpxpath -v Description /gpx/metadata/desc track.gpx

  Add or update the value of the path '/gpx/metadata/desc' from the track.gpx file. The resulting GPX-file will be sent to standard output.

gpxpath -v 48.7 /gpx/wpt/ele track.gpx >track1.gpx

  Update the value of ALL existing '/gpx/wpt/ele' paths from the track.gpx file. The result will be written in track1.gpx.
```

---

## gpxwind

```text
Usage: gpxwind [OPTION].. [N|NE|E|SE|S|SW|W|NW] [FILE]
Show the impact of the wind direction on the track or route in the GPX-file.

   -?, --help                     display this help and exit
       --version                  display version and exit
   -m, --mode=summary|full|plot   mode for showing the impact

Show the wind impact on a track or route
```

Note: the tool is intended for cyclists. 

Examples:
```text
gpxwind N track.gpx

  Show the impact of a northern wind on the track. The tool shows the headwind and tailwind distance of the routes and/or tracksegments in the track.gpx file.

gpxwind -mfull SE track.gpx

  Show the impact of a southeastern wind on the track. The tool shows the head-, cross- and tailwind distances of the elements in the track.gpx file.

gpxwind -mplot W track.gpx | gnuplot

  Generate a gpxwind.png image file with the track and the impact of a western wind on the track.gpx file. Headwind is drawn in a red color, tailwind in a green color.
  This option works best with only one route or tracksegment in the GPX file.
  
```

Requirements:
  * [GnuPlot](http://www.gnuplot.info/) for plotting

---

